Schema Developer Guide

Definitions

A LearningStore enumeration (referred to as “enumeration” in the rest of this doc) is an entity that consists of a set of named constants.

A LearningStore item (referred to as “item” in the rest of this doc) is an entity that maintains a set of properties. An item type defines the set of properties (and the types of the properties) maintained by an item. Every item is based on exactly one item type.

A LearningStore view (referred to as “view” in the rest of this doc) defines a “virtual table” in the database that contains a subset of data from the database. A view can contain information from different items, and it can even contain calculated values (e.g., the number of items of a particular item type).

A LearningStore right (referred to as "right" in the rest of this doc) defines the security of an action.  The following rights are built-in:

Custom rights can also be defined.

A LearningStore schema (referred to as "schema" in the rest of this doc) contains a set of enumeration, item type, view, and right definitions.  The base schema contains the definitions that are common across all MLC schemas.  The application schema contains extensions to the base schema that are specific to an application.

A schema identifier defines an entity in a schema.  It must follow these rules:

Identifiers are case-sensitive.  LearningStore often uses identifiers as SQL Server identifiers.  If SQL Server is configured with a collation in which two unique identifiers become identical, LearningStore is not guaranteed to work.

 

Schema compiler

The schema compiler is a command-line tool that takes an XML file containing an application schema as input, and outputs the following:

 

Schema definition file

A schema definition file is an XML file that contains a single StoreSchema element.

StoreSchema element: root element

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Enum 0..* Defines a new enumeration.
ItemType 0..* Defines a new item type.
View 0..* Defines a new view.
Right 0..* Defines a new right.
ExtendItemType 0..* Extends a currently-existing item type.
ExtendView 0..* Extends a currently-existing view.
ExtendRight 0..* Extends a currently-existing right.
SqlBefore 0..* Additional SQL statements that should be included before any table/function definitions (in character data).  To start a new batch, use "GO" in the SQL statements.
SqlAfter 0..* Additional SQL statements that should be included after all table/function definitions (in character data).  To start a new batch, use "GO" in the SQL statements.

 

StoreSchema/Enum element: defines a new enumeration

Attributes:
Name Type Required? Description
Name xs:string yes Name of the enumumeration.

This must follow the rules for schema identifiers.  It must also be unique across all enumerations/item types/views/rights in the schema.


Character data: None

Child elements:

Name Multiplicity Description
Values 1 Defines the name/value pairs in the enumeration.
Documentation 0..1 Documentation for the enum in the C# helper file.

 

StoreSchema/Enum/Values element: defines the values in an enumeration

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Value 1..* Defines the name/value pairs in the enumeration.

 

StoreSchema/Enum/Values/Value element: defines a single name/value pair in an enumeration

Attributes:
Name Type Required? Description
Name xs:string Yes Name of the value.

This must follow the rules for schema identifiers.  It must also be unique across all values in this enumeration.

Value xs:integer Yes Integer value.  Must be unique across all values in this enumeration.

Character data: None

Child elements:

Name Multiplicity Description
Documentation 0..1 Documentation for the value in the C# helper file (in character data).  Empty namespace.

 

StoreSchema/Enum/Documentation element: defines documentation for the enum in the C# helper file

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Summary 0..1 Summary (in character data).  Empty namespace.
Remarks 0..1 Remarks (in character data).  Empty namespace.

 

StoreSchema/ItemType element: Defines a new item type

Attributes:
Name Type Required? Description
Name xs:string yes Name of the item type.  Maps to the name of the table in the database.

This must follow the rules for schema identifiers.  It must also be unique across all enumerations/item types/views/rights in the schema.


Character data: None

Child elements:

Name Multiplicity Description
Properties 0..1 Defines properties on the item type
GrantAddRight 0..1 Allows a set of users to add items of this item type.
GrantDeleteRight 0..1 Allows a set of users to delete items of this item type.
GrantUpdateRight 0..1 Allows a set of users to update items of this item type.
GrantQueryRight 0..1 Allows a set of users to query for items of this item type.  See StoreSchema/View/GrantQueryRight for details.
Indexes 0..1 Indexes on the item type.
SqlAfter 0..1 Additional SQL statements that should be included after all table/function definitions (in character data).  To start a new batch, use "GO" in the SQL statements.
Documentation 0..1 Documentation for the class in the C# helper file.

 

StoreSchema/ItemType/Properties element: Defines the properties for an item type

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Property 0..* Defines a property on this item type.

 

StoreSchema/ItemType/Properties/Property element: Defines a single property for an item

Attributes:
Name Type Required? Description
Name xs:string yes Name of the property.

This must follow the rules for schema identifiers.  It must also be unique across all properties on this item.  It must not be "UserKey" or "Id".

Type xs:string yes Type of the property.  Can be one of the following:
  • "ItemIdentifier"
  • "String"
  • "Boolean"
  • "DateTime"
  • "Single"
  • "Double"
  • "Xml"
  • "Enum"
  • "Int32"
  • "ByteArray"
  • "Guid"
EnumName xs:string yes if Type="Enum" Type of the enumeration value returned in this column.

Must refer to an enumeration in the schema (i.e., a StoreSchema/Enum element in the current file or in the base schema).

ReferencedItemTypeName xs:string yes if Type="ItemIdentifier" Type of the item identifier returned in this column.

Must refer to an item type in the schema (i.e., a StoreSchema/ItemType element in the current file or in the base schema).

Length xs:integer no Length of the String/array.  If not specified, then the length is unlimited.

Valid only when Type="String" or Type="ByteArray".  For String, it must be between 1 and (Int32.MaxValue - 2) / 2.  For ByteArray, it must be between 1 and (Int32.MaxValue - 2).

Nullable xs:boolean no Can the property contain null?  The default is "false".
CascadeDelete xs:boolean no Valid only when Type="ItemIdentifier".  Is this item automatically deleted when the referenced item is deleted?  The default is "false".

Character data: None

Child elements:

Name Multiplicity Description
Default 0..1 Defines the default value for the property.  If this is not included, then the property doesn't have a default value.
Constraints 0..1 Constraints for the property.
Documentation 0..1 Documentation for the property

 

StoreSchema/ItemType/Properties/Property/Default element: Defines the default value for a property on an item type.

Attributes:
Name Type Required? Description
Null xs:boolean no True if the default value for the property should be null.  If not provided, then the default value is assumed not to be null.

Character data: Default value of the property, or empty if the Null attribute is true.  The format depends on the Type attribute of the property:

Child elements: None

 

StoreSchema/ItemType/Properties/Property/Constraints element: Defines the constraints on an item type property

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Constraint 0..* Defines a constraint on the property.

 

StoreSchema/ItemType/Properties/Property/Constraints/Constraint element: Defines a constraint on an item type property.

Attributes: None

Character data: A UNIQUE or CHECK constraint definition, as described in the SQL CREATE TABLE command.

Examples:

UNIQUE

CHECK(Score>0)

Child elements: None

 

StoreSchema/ItemType/Properties/Property/Documentation element: defines documentation for the item type property in the C# helper file

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Summary 0..1 Summary (in character data).  Empty namespace.
Remarks 0..1 Remarks (in character data).  Empty namespace.

 

StoreSchema/ItemType/GrantAddRight element: Allows a set of users to add items of this item type

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Expression 0..* Allows users based on an expression.

The security from all of the elements are "or"-ed together.  For example, if two "Expression" child elements exist, then at least one needs to return "success" for the user to gain access.

 

StoreSchema/ItemType/GrantAddRight/Expression element: Allows a set of users to add items of this item type -- security defined by an expression

Attributes: None

Character data: An expression that returns a bit.  If the bit has the value "1", the user should be granted access.  The expression must be able to appear within a scalar function (see SQL documentation for more details).  The following parameters are available for use by the expression:

Example:

CASE WHEN @UserKey='Bob' THEN 1 ELSE 0 END

Child elements: None

 

StoreSchema/ItemType/GrantDeleteRight element: Allows a set of users to delete items of this item type

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Expression 0..* Allows users based on an expression.

The security from all of the elements are "or"-ed together.  For example, if two "Expression" child elements exist, then at least one needs to return "success" for the user to gain access.

 

StoreSchema/ItemType/GrantDeleteRight/Expression element: Allows a set of users to delete items of this item type -- security defined by an expression

Attributes: None

Character data: An expression that returns a bit.  If the bit has the value "1", the user should be granted access.  The expression must be able to appear within a scalar function (see SQL documentation for more details).  The following parameters are available for use by the expression:

Example:

CASE WHEN @UserKey='Bob' THEN 1 ELSE 0 END

Child elements: None

 

StoreSchema/ItemType/GrantUpdateRight element: Allows a set of users to update items of this item type

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Expression 0..* Allows users based on an expression.

The security from all of the elements are "or"-ed together.  For example, if two "Expression" child elements exist, then at least one needs to return "success" for the user to gain access.

 

StoreSchema/ItemType/GrantUpdateRight/Expression element: Allows a set of users to update items of this item type -- security defined by an expression

Attributes: None

Character data: An expression that returns a bit.  If the bit has the value "1", the user should be granted access.  The expression must be able to appear within a scalar function (see SQL documentation for more details).  The following parameters are available for use by the expression::

Example:

CASE WHEN @UserKey='Bob' THEN 1 ELSE 0 END

Child elements: None

 

StoreSchema/ItemType/Indexes element: Defines the indexes for an item type

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Index 0..* Defines an index on this item type.

 

StoreSchema/ItemType/Indexes/Index element: Defines an index on an item type.

Attributes: None

Character data: A CREATE INDEX statement defining the index. 

Example:

CREATE INDEX UserKeyIndex ON UserItem([Key])

Child elements: None

 

StoreSchema/ItemType/Documentation element: defines documentation for the item type in the C# helper file

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Summary 0..1 Summary (in character data).  Empty namespace.
Remarks 0..1 Remarks (in character data).  Empty namespace.

 

StoreSchema/View element: defines a view

Attributes:
Name Type Required? Description
Name xs:string yes Name of the view.

This must follow the rules for schema identifiers.  It must also be unique across all enumerations/item types/views/rights in the schema.


Character data: None

Child elements:

Name Multiplicity Description
Parameters 0..1 Defines the parameters needed by the view
Columns 1 Defines the columns returned by the view.
Implementation 1 Defines the SQL function that implements the view.
GrantQueryRight 0..1 Allows a set of users to perform queries on the view.
Documentation 0..1 Documentation for the view.

 

StoreSchema/View/Parameters element: defines the parameters used by a view

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Parameter 0..* Defines a parameter that is used by the view.

 

StoreSchema/View/Parameters/Parameter element: defines a single parameter used by a view

Attributes:
Name Type Required? Description
Name xs:string Yes Name of the parameter.

This must follow the rules for schema identifiers.  It must also be unique across all columns and parameters in this view.  It must not be "UserKey".

Type xs:string Yes Type of the parameter.  Can be one of the following:
  • "ItemIdentifier"
  • "String"
  • "Boolean"
  • "DateTime"
  • "Single"
  • "Double"
  • "Xml"
  • "Enum"
  • "Int32"
  • "ByteArray"
  • "Guid"
EnumName xs:string Yes if Type="Enum" Type of the enumeration value for this parameter.

Must refer to an enumeration in the schema (i.e., a StoreSchema/Enum element in the current file or in the base schema).

ReferencedItemTypeName xs:string Yes if Type="ItemIdentifier" Type of the item identifier for this parameter.

Must refer to an item type in the schema (i.e., a StoreSchema/ItemType element in the current file or in the base schema).


Character data: None

Child elements:

Name Multiplicity Description
Documentation 0..1 Documentation for this parameter.

 

StoreSchema/View/Parameters/Parameter/Documentation element: defines documentation for the parameter in the C# helper file

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Summary 0..1 Summary (in character data).  Empty namespace.
Remarks 0..1 Remarks (in character data).  Empty namespace.

 

StoreSchema/View/Columns element: defines the columns returned by a view

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Column 1..* Defines a column that is returned by the view.

Must be declared in the same order as the columns are returned in the view implementation.

 

StoreSchema/View/Columns/Column element: defines a single column returned by a view

Attributes:
Name Type Required? Description
Name xs:string Yes Name of the column.

This must follow the rules for schema identifiers.  It must also be unique across all columns and parameters in this view.

Type xs:string Yes Type of the property.  Can be one of the following:
  • "ItemIdentifier"
  • "String"
  • "Boolean"
  • "DateTime"
  • "Single"
  • "Double"
  • "Xml"
  • "Enum"
  • "Int32"
  • "ByteArray"
  • "Guid"
EnumName xs:string Yes if Type="Enum" Type of the enumeration value returned in this column.

Must refer to an enumeration in the schema (i.e., a StoreSchema/Enum element in the current file or in the base schema).

ReferencedItemTypeName xs:string Yes if Type="ItemIdentifier" Type of the item identifier returned in this column.

Must refer to an item in the schema (i.e., a StoreSchema/ItemType element in the current file or in the base schema).


Character data: None

Child elements:

Name Multiplicity Description
Documentation 0..1 Documentation for this column

 

StoreSchema/View/Columns/Column/Documentation element: defines documentation for the column in the C# helper file

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Summary 0..1 Summary (in character data).  Empty namespace.
Remarks 0..1 Remarks (in character data).  Empty namespace.

 

StoreSchema/View/Implementation: Defines an implementation for a view

Attributes: None

Character data: A SELECT statement that defines the view.  The SELECT statement must be able to appear within an inline table-valued function (see SQL documentation for more details).  The following parameters are available for use by the SELECT statement:

The SELECT statement must return the columns specified by the corresponding StoreSchema/View/Column elements.  The types and names of the columns must match the information in those elements.

Example:

Child elements: None

 

StoreSchema/View/GrantQueryRight element: Defines security for the "Query" operation

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Expression 0..* Defines security using an expression.

The security from all of the elements are "or"-ed together.  For example, if two "Expression" child elements exist, then at least one needs to return "success" for the user to gain access.

 

StoreSchema/View/GrantQueryRight/Expression element: Defines security for the "Query" operation -- security defined by an expression

Attributes: None

Character data: An expression that returns a bit.  If the bit has the value "1", the user should be granted access.  The expression must be able to appear within a scalar function (see SQL documentation for more details).  The following parameters are available for use by the expression:

Example:

CASE WHEN @UserKey='Bob' THEN 1 ELSE 0 END

Child elements: None

 

StoreSchema/View/Documentation element: defines documentation for the view in the C# helper file

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Summary 0..1 Summary (in character data).  Empty namespace.
Remarks 0..1 Remarks (in character data).  Empty namespace.

 

StoreSchema/Right element: defines a right

Attributes:
Name Type Required? Description
Name xs:string yes Name of the right.

This must follow the rules for schema identifiers.  It must also be unique across all enumerations/item types/views/rights in the schema.


Character data: None

Child elements:

Name Multiplicity Description
Parameters 0..1 Defines the parameters needed by the right.  See StoreSchema/View/Parameters for details.

Example: If a user should have a particular right for one Package, but not to others, then the PackageId should be a parameter to the right.

Grant 0..1 Defines security for the right.
Documentation 0..1 Documentation for the right.

 

StoreSchema/Right/Documentation element: defines documentation for the right in the C# helper file

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Summary 0..1 Summary (in character data).  Empty namespace.
Remarks 0..1 Remarks (in character data).  Empty namespace.

 

StoreSchema/Right/Grant element: Defines security for the right

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Expression 0..* Defines security using an expression.

The security from all of the elements are "or"-ed together.  For example, if two "Expression" child elements exist, then at least one needs to return "success" for the user to have the right.

 

StoreSchema/Right/Grant/Expression element: Defines security for a right -- security defined by an expression

Attributes: None

Character data: An expression that returns a bit.  If the bit has the value "1", the user should be granted access.  The expression must be able to appear within a scalar function (see SQL documentation for more details).  The following parameters are available for use by the expression:

Example:

CASE WHEN @UserKey='Bob' THEN 1 ELSE 0 END

Child elements: None

 

StoreSchema/ExtendItemType element: Extends a currently-existing item type

Attributes:
Name Type Required? Description
Name xs:string yes Name of the item type to be extended.

Must refer to an item type in the base schema (i.e., a StoreSchema/ItemType in the base schema).  Must be unique across all ExtendItemType elements in the file (i.e., an item type can only be extended once).

ReplaceIndexes xs:boolean no If true, then all indexes on the currently-existing item type are ignored.  Default is "false".

Character data: None

Child elements:

Name Multiplicity Description
Properties 0..1 Defines additional or updated properties on this item type.
GrantAddRight 0..1 Allows a set of users to add items of this type.  See StoreSchema/ItemType/GrantAddRight for details.
GrantDeleteRight 0..1 Allows a set of users to delete items of this type.  See StoreSchema/ItemType/GrantDeleteRight for details.
GrantUpdateRight 0..1 Allows a set of users to update items of this type.  See StoreSchema/ItemType/GrantUpdateRight for details.
GrantQueryRight 0..1 Allows a set of users to perform queries on the default view of the item type.  See StoreSchema/ItemType/GrantQueryRight for details.
Indexes 0..1 Defines additional indexes on this item type.  See StoreSchema/ItemType/Indexes for details.
SqlAfter 0..1 Additional SQL statements that should be included after all table/function definitions (in character data).
Documentation 0..1 Adds additional documentation for this item.  See StoreSchema/ItemType/Documentation for details.

 

StoreSchema/ExtendItemType/Properties element: Defines additional or updated properties for an item type

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Property 0..* Defines a new property on this item type.  See StoreSchema/ItemType/Properties/Property for details.  A default value is required.
ExtendProperty 0..* Extends a currently-existing property on this item type.

 

StoreSchema/ExtendItemType/Properties/ExtendProperty element: Extends a currently-existing property

Attributes:
Name Type Required? Description
Name xs:string yes Name of the property.

Must refer to a property on the item type on the base schema (i.e., a StoreSchema/ItemType/Properties/Property in the base schema).  Must be unique across all ExtendProperty elements in the item type (i.e., a property can only be extended once).


Character data: None

Child elements:

Name Multiplicity Description
Documentation 0..1 Additional documentation for the property.  See StoreSchema/ItemType/Properties/Property/Documentation for details.

 

StoreSchema/ExtendView element: Extends a currently-existing view.

Attributes:
Name Type Required? Description
Name xs:string yes Name of the view to be extended.

Must refer to a view in the base schema (i.e., a StoreSchema/View in the base schema).  Must be unique across all ExtendView elements in the file (i.e., a view can only be extended once).


Character data: None

Child elements:

Name Multiplicity Description
GrantQueryRight 0..1 Allows a set of users to to perform queries on the view.  See StoreSchema/View/GrantQueryRight for details.
Documentation 0..1 Adds additional documentation for the view.  See StoreSchema/View/Documentation for details.

 

StoreSchema/ExtendRight element: Extends a currently-existing right.

Attributes:
Name Type Required? Description
Name xs:string yes Name of the right to be extended.

Must refer to a right in the base schema (i.e., a StoreSchema/Right in the base schema).  Must be unique across all ExtendRight elements in the file (i.e., a right can only be extended once).


Character data: None

Child elements:

Name Multiplicity Description
Parameters 0..1 Defines additional or updated parameters on this right.
Grant 0..1 Grants a set of users the right.  See StoreSchema/Right/Grant for details.
Documentation 0..1 Adds additional documentation for the right.  See StoreSchema/Right/Documentation for details.

 

StoreSchema/ExtendRight/Parameters element: Defines additional or updated parameters for a right

Attributes: None

Character data: None

Child elements:

Name Multiplicity Description
Parameter 0..* Defines a new parameter on this right.  See StoreSchema/Right/Parameters/Parameter for details.
ExtendParameter 0..* Extends a currently-existing parameter on this right.

 

StoreSchema/ExtendRight/Parameters/ExtendParameter element: Extends a currently-existing parameter

Attributes:
Name Type Required? Description
Name xs:string yes Name of the parameter.

Must refer to a parameter on a right on the base schema (i.e., a StoreSchema/Right/Parameters/Parameter in the base schema).  Must be unique across all ExtendParameter elements in the right (i.e., a parameter can only be extended once).


Character data: None

Child elements:

Name Multiplicity Description
Documentation 0..1 Additional documentation for the parameter.  See StoreSchema/Right/Parameters/Parameter/Documentation for details.